简·工具箱

Jian Toolbox — 部署 · 使用 · 维护指南

一、项目简介

「简」是一款自托管的多功能个人助理工具箱，集成备忘录、记账本、收藏夹三大核心模块，支持多用户体系与管理员后台。

技术栈：Python 3.11 + Flask + SQLite + Gunicorn
部署方式：Docker Compose 一键部署
访问方式：浏览器访问，支持 PWA 安装到桌面
容器镜像：crpi-y8xug7uzjvd1zqiv.cn-chengdu.personal.cr.aliyuncs.com/dafili/personal-assistant:latest

二、环境要求

一台 Linux 服务器 / NAS（如飞牛云、群晖、Ubuntu 等）
已安装 Docker 与 Docker Compose
可选：域名 + 反向代理（Nginx / 阿里云 CDN 等）

三、部署步骤

3.1 拉取项目文件

将项目文件放置于服务器目录，例如：

/vol1/1000/docker/personal-assistant/
├── app.py
├── auth.py
├── config.py
├── models.py
├── requirements.txt
├── docker-compose.yml
├── Dockerfile
├── icon.png
├── data/                  # 自动生成：app.db + app.log
├── routes/
│   ├── __init__.py
│   ├── admin.py
│   ├── bookmarks.py
│   ├── ledger.py
│   ├── memo.py
│   └── nav.py
└── templates/
    ├── admin.html
    ├── bookmarks.html
    ├── ledger.html
    ├── login.html
    ├── memo.html
    └── nav.html

3.2 启动容器

cd /vol1/1000/docker/personal-assistant
sudo docker compose up -d

首次启动会自动拉取镜像并创建容器。启动后可通过 http://服务器IP:5000 访问。

3.3 配置环境变量（可选）

# 在 docker-compose.yml 同级目录创建 .env 文件
SECRET_KEY=your-random-secret-key
DEFAULT_PASS=your-default-password

默认管理员账户：用户名 默认，密码 1234（如未设置 DEFAULT_PASS）。

3.4 配置反向代理（推荐）

使用 Nginx 或阿里云 CDN 将域名指向 http://127.0.0.1:5000，即可通过域名访问。

提示：如果使用 HTTPS，请确保反代层面配置 SSL 证书，应用本身运行在 HTTP 模式。

四、功能模块使用

4.1 备忘录

新建备忘录：点击侧边栏「新建备忘录」按钮。
编辑模式：可视化编辑（富文本）、源码模式、预览模式。
插入代码块：点击工具栏「代码」按钮，在出现的灰色框中粘贴代码。
复制代码：鼠标悬停代码块，点击右上角「复制」按钮即可一键复制。
搜索：使用顶部的搜索框按文件名搜索。
删除：点击备忘录右侧 ✖ 按钮，输入密码确认删除。
夜间模式：点击右上角 ⏾ 按钮切换深色主题。

4.2 记账本

记一笔：点击右下角 + 按钮，填写日期、类别（收入/支出）、金额、备注。
月度统计：顶部自动显示本月收入、支出、结余。
切换月份：点击 ◀ ▶ 按钮切换查看不同月份。
编辑/删除：点击列表右侧 ✎ 或 ✖ 按钮，需要输入密码验证。
PushDeer 推送：点击右上角「PushDeer」绑定你的 Key，记账后将自动推送通知到手机。
导出 CSV：可通过管理员后台导出记账数据。

4.3 收藏夹

添加收藏：点击右下角 + 按钮，填写标题、链接、标签（逗号分隔）、备注。
标签筛选：顶部下拉框按标签过滤收藏。
搜索：顶部搜索框支持关键词搜索，匹配项高亮显示。
一键复制链接：点击 📋 按钮将链接复制到剪贴板。
导入浏览器书签：点击顶部「导入」按钮，选择从 Chrome/Edge 导出的 bookmarks.html 文件。
导出书签：点击「导出HTML」下载标准书签格式文件。
链接检测：点击「检测链接」按钮，自动检测所有收藏链接是否仍可访问，失效链接标记红色。
拖拽排序：长按左侧 ≡ 图标拖动调整顺序。

4.4 导航页

首页展示内置工具入口（备忘录、记账本、收藏夹）及自定义快捷链接。
添加链接：点击 + 按钮，填写名称、图标（emoji）、链接地址。
管理链接：点击 − 按钮可删除已添加的自定义链接。

4.5 管理员后台

访问路径：/admin
用户管理：查看所有用户、重置密码、删除用户（含其所有数据）。
数据导入：为指定用户导入记账 CSV、收藏 CSV、备忘录 ZIP。
数据导出：导出指定用户或全部用户的记账、收藏、备忘录数据。

五、日常维护

5.1 容器管理

# 查看容器状态
sudo docker compose ps

# 重启容器（修改代码后必须执行）
sudo docker compose restart app

# 查看日志
sudo docker compose logs -f --tail=50 app

# 停止容器
sudo docker compose down

# 启动容器
sudo docker compose up -d

重要：修改任何代码或模板后，必须执行 sudo docker compose restart app 重启容器才能生效。仅刷新浏览器不会加载新代码。

5.2 数据备份

# 备份整个数据目录
cp -r /vol1/1000/docker/personal-assistant/data /backup/data_$(date +%Y%m%d)

# 仅备份数据库
cp /vol1/1000/docker/personal-assistant/data/app.db /backup/app_$(date +%Y%m%d).db

建议定期备份 data/ 目录，该目录包含 SQLite 数据库和应用日志。

5.3 更新镜像

cd /vol1/1000/docker/personal-assistant
sudo docker compose pull
sudo docker compose up -d

更新前请先备份数据。

5.4 常见问题

Q：页面样式异常或功能不正常？
A：清除浏览器缓存（Ctrl+Shift+Delete），然后强制刷新（Ctrl+Shift+R）。

Q：忘记了管理员密码？
A：进入容器重置：

sudo docker exec -it personal-assistant python3 -c "
from auth import hash_password
from models import get_db
with get_db() as db:
    db.execute('UPDATE users SET password_hash=? WHERE username=?', (hash_password('新密码'), '默认'))
    db.commit()
print('密码已重置')
"

Q：容器启动失败？
A：检查端口 5000 是否被占用，检查 data/ 目录权限。
Q：代码块保存后丢失格式？
A：确保后端 routes/memo.py 中 ALLOWED_TAGS 包含 'pre' 和 'code'。

六、安全建议

首次登录后立即修改默认管理员密码。
配置反向代理时开启 HTTPS。
定期备份数据库。
如暴露于公网，建议配合 fail2ban 等工具防护暴力破解。
环境变量 SECRET_KEY 请使用随机字符串，不要使用默认值。

七、联系与反馈

如有问题或建议，可通过以下方式联系：

Gitee：DAFILI
邮箱：664311568@qq.com